Prev Next

Author: John West
Posted: 7/25/2006 5:19:12 PM

Important Update:

Sitecore developers have reported performance issues with the ISAPI filter from IISmods under heavy load. One option to consider is ISAPI_Rewrite from Helicon Tech:

http://www.helicontech.com/download/#isapi_rewrite

The "Lite" version should be sufficient for this requirement.  This filter works much like IISmods but the configuration file is httpd.ini in the installation directory (typically C:\Program Files\Helcion\httpd.ini):

 

This document describes techniques supporting URLs which are friendlier than Sitecore’s default hierarchical URLs by excluding the .html extension. This technique should work with all versions of the product. Sitecore internally will continue to generate URLs with the .html extension, but marketing literature, email and other resources can be distributed without the extension. This solution also supports Sitecore aliases, so assuming the alias /jobs has been created to reference the /hr/jobs item, the following URLs should all display the same content:

/hr/jobs

/hr/jobs/

/hr/jobs.html

/jobs

/jobs/

/jobs.html

Any form of URL should also support query string parameters.

Additional resources on this topic include:

• http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/54c41c83-3723-4695-9bf1-9f7b1f674be0.mspx?mfr=true
  
• http://www.microsoft.com/resources/documentation/Windows/2000/server/reskit/en-us/Default.asp?url=/resources/documentation/Windows/2000/server/reskit/en-us/iisbook/c01_isapi_filters.asp

Overview 

Details on ISAPI filters are out of scope for this document, but basically when an HTTP request is received by IIS, ISAPI filters are invoked to implement custom processing before the web server handles the request. When ASP.NET is installed it registers such an ISAPI filter visible on the ISAPI Filters tab in the properties of the Web Sites entry in the IIS MMC

Installing FrontPage extensions may register another ISAPI filter on individual web sites:

The Configuration button on the Home Directory tab also maps specific extensions such as .html to specific processors. This feature can be used to map various extensions and even requests with no extension to ASP.NET for processing. Many requests are intentionally ignored by ASP.NET such as graphics and static .html files as .NET processing would degrade performance without adding value in most solutions.

An alternative to mapping every request to the .NET framework is to install another ISAPI plug-in which intercepts requests before the ASP.NET ISAPI and adds the .html extension if none is present.

Implementation 

There are several free ISAPI rewriting tools available on the Internet. The solution described below uses Mod_Rewrite from http://www.iismods.com. To configure:

• Read http://www.iismods.com/url-rewrite/documentation.htm.
  
• Download from http://www.iismods.com/download.htm.
  
• Copy the DLL and the INI files to a directory on the server such as E:\windows\system32\inetsrv.
  
       a. Ensure the owner of the ASP.NET worker process (by default ASPNET on Windows XP, NETWORK SERVICE on Windows 2003) and the IIS impersonation user (by default IUSR_<machinename>) have read and execute permissions on the DLL and read permission on the INI.
  
        b. To enable logging, the ASP.NET worker process must also have write access to this directory, or at least the mod_rewrite.txt file therein.
  
• Update the INI file as follows:

#http://www.iismods.com/url-rewrite/documentation.htm

Debug 0

Reload 5000

RewriteRule ^(/sitecore.*)$ $1 [l]

RewriteRule ^/([^\.\?]+)/?(\?.*)?$ /$1.html$2 [l]

The first rule causes any request for /sitecore or anything beneath to be ignored and such requests will not be processed further by the rewriter. The second handles all other requests with no extension, though the regular expression is complicated by support for query string parameters. Rules are executed against the requested URL minus the protocol and domain. Rule syntax is described at http://www.iismods.com/url-rewrite/documentation.htm but basically the first space-delimited token is a regular expression (see http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/cpconRegularExpressionsLanguageElements.asp), the second token indicates how requests which match that expression should be translated and the third (optional) token provides qualifying options for the rules. Regular expressions used are case-insensitive. To enable logging change “Debug 0” to “Debug 1”; assuming the ASP.NET worker process has permission, once the filter is running this will create mod_rewrite.txt in the same directory which could have an impact on performance and disk consumption.

The following can apparently be performed on the Web Sites item in IIS MMC or on individual Web Sites.

The rewrite ISAPI must be executed before IIS determines whether or not to process the request with .NET. It seems logical that the rewrite filter should add the .html extension before IIS makes this decision. It is not clear how to control the order in which the different filters execute as priority is set in the DLL. It’s intended that ISAPI filters listed first for a given priority are executed first but testing indicates order doesn’t seem to have much impact.

Since the ASP.NET ISAPI is registered on Web Sites it seems logical to register the rewrite ISAPI there and move it above the ASP.NET ISAPI as described below. Access the ISAPI Filters tab of the properties pallet of the Web Sites entry in the IIS MMC:

Press the Add button, name the filter and browse for the DLL:

It may not be possible to “Move Up” at this point; close MMC, restart IIS, open a browser and request a page from the site. If the browser shows “Service Unavailable”, the event log probably contains an entry indicating the cause, which is likely permissions on the DLL or INI file (see above). http://blogs.msdn.com/david.wang/archive/2005/06/21/HOWTO_Diagnose_and_Fix_Common_ISAPI_Filter_Installation_Failures.html provides additional information on resolving these types of issues. An HTTP 404 error generally indicates a typo or other error in the INI file.

Once any issues are resolved, return to the ISAPI Filters tab and move the rewrite ISAPI to the top of the list:

Known Issues 

If the rewrite ISAPI filter is applied to the Web Sites entry rather than a specific site so that it will be invoked before the .NET ISAPI filter, the impact on other sites hosted on the same server must be considered, which may result in use of RewriteCond instead of RewriteRule and/or more complex regular expressions.

An approach to marketing URLs which avoids the need for an ISAPI filter is uses the HTTP 404 page instead. This technique is described in NotFound.html.cs under http://groups.yahoo.com/group/sitecore/files.

If default documents such as default.html are being used in other sites or subdirectories, for instance standalone ASP.NET solutions, the regular expression may need additional work. As an example, if the URL /forms is used to access /forms/default.html, the following rule might be inserted between the existing rules:

RewriteRule ^(/sitecore.*)$ $1 [l]

RewriteRule ^(/forms.*)$ $1 [l]

RewriteRule ^/([^\.\?]+)/?(\?.*)?$ /$1.html$2 [l]

Rules here may correspond to the IgnoreUrlPrefixes setting in web.config.

There is one INI file per copy of the DLL. Theoretically, if different INI files are required for different sites, the existing DLL and INI can be copied to a different directory with appropriate permissions and registered for the different sites, but this approach has not been tested.

Uninstallation

To uninstall:

1. Remove the ISAPI filter anywhere it is registered in the IIS MMC.
   
2. Delete any copies of the DLL, INI and TXT files.

Prev Next